core.triggers ¶

This module includes function decorators and Trigger subclasses to simplify Jython rule definitions.

If using a build of openHAB prior to S1566 or 2.5M2, see System Started for a System started workaround. For everyone, see System Shuts Down for a method of executing a function when a script is unloaded, simulating a System shuts down trigger. Along with the when decorator, this module includes the following Trigger subclasses (see Extensions for more details):

CronTrigger - fires based on cron expression
ItemStateChangeTrigger - fires when the specified Item’s state changes
ItemStateUpdateTrigger - fires when the specified Item’s state is updated
ItemCommandTrigger - fires when the specified Item receives a Command
GenericEventTrigger - fires when the specified occurs
ItemEventTrigger - fires when am Item reports an event (based on GenericEventTrigger)
ThingEventTrigger - fires when a Thing reports an event (based on GenericEventTrigger)
ThingStatusChangeTrigger - fires when the specified Thing’s status changes (requires S1636, 2.5M2 or newer)
ThingStatusUpdateTrigger - fires when the specified Thing’s status is updated (requires S1636, 2.5M2 or newer)
ChannelEventTrigger - fires when a Channel reports an event
DirectoryEventTrigger - fires when a directory’s contents changes
ItemRegistryTrigger - fires when the specified Item registry event occurs
ItemAddedTrigger - fires when an Item is added (based on ItemRegistryTrigger)
ItemRemovedTrigger - fires when an Item is removed (based on ItemRegistryTrigger)
ItemUpdatedTrigger - fires when an Item is updated (based on ItemRegistryTrigger)
StartupTrigger - fires when the rule is activated (implemented in Jython and requires S1566, 2.5M2 or newer)

core.triggers.when(target)¶

This function decorator creates triggers attribute in the decorated function that is used by the rule decorator when creating a rule.

The when decorator simplifies the use of many of the triggers in this module and allows for them to be used with natural language similar to what is used in the rules DSL.

See Decorators for examples of how to use this decorator.

Examples

@when("Time cron 55 55 5 * * ?")
@when("Item Test_String_1 changed from 'old test string' to 'new test string'")
@when("Item gMotion_Sensors changed")
@when("Member of gMotion_Sensors changed from ON to OFF")
@when("Descendent of gContact_Sensors changed from OPEN to CLOSED")
@when("Item Test_Switch_2 received update ON")
@when("Item Test_Switch_1 received command OFF")
@when("Thing kodi:kodi:familyroom changed")
@when("Thing kodi:kodi:familyroom changed from ONLINE to OFFLINE")# requires S1636, 2.5M2 or newer
@when("Thing kodi:kodi:familyroom received update ONLINE")# requires S1636, 2.5M2 or newer
@when("Channel astro:sun:local:eclipse#event triggered START")# must use a Channel of kind Trigger
@when("System started")# requires S1566, 2.5M2 or newer ('System shuts down' has not been implemented)

Parameters: target (string) – the rules DSL-like formatted trigger expression to parse

class core.triggers.ItemStateUpdateTrigger(itemName, state=None, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds an ItemStateUpdateTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemStateUpdateTrigger("MyItem", "ON", "MyItem-received-update-ON").trigger]
MyRule.triggers.append(ItemStateUpdateTrigger("MyOtherItem", "OFF", "MyOtherItem-received-update-OFF").trigger)

Parameters

itemName (string) – name of item to watch for updates
state (string) – (optional) trigger only when updated TO this state
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemStateChangeTrigger(itemName, previousState=None, state=None, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds an ItemStateChangeTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemStateChangeTrigger("MyItem", "OFF", "ON", "MyItem-changed-from-OFF-to-ON").trigger]
MyRule.triggers.append(ItemStateChangeTrigger("MyOtherItem", "ON", "OFF","MyOtherItem-changed-from-ON-to-OFF").trigger)

Parameters

itemName (string) – name of item to watch for changes
previousState (string) – (optional) trigger only when changing FROM this state
state (string) – (optional) trigger only when changing TO this state
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemCommandTrigger(itemName, command=None, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds an ItemCommandTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemCommandTrigger("MyItem", "ON", "MyItem-received-command-ON").trigger]
MyRule.triggers.append(ItemCommandTrigger("MyOtherItem", "OFF", "MyOtherItem-received-command-OFF").trigger)

Parameters

itemName (string) – name of item to watch for commands
command (string) – (optional) trigger only when this command is received
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ThingStatusUpdateTrigger(thingUID, status=None, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a ThingStatusUpdateTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ThingStatusUpdateTrigger("kodi:kodi:familyroom", "ONLINE").trigger]

Parameters

thingUID (string) – name of the Thing to watch for status updates
status (string) – (optional) trigger only when Thing is updated to this status
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule.

Type: Trigger

class core.triggers.ThingStatusChangeTrigger(thingUID, previousStatus=None, status=None, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a ThingStatusChangeTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ThingStatusChangeTrigger("kodi:kodi:familyroom", "ONLINE", "OFFLINE).trigger]

Parameters

thingUID (string) – name of the Thing to watch for status changes
previousStatus (string) – (optional) trigger only when Thing is changed from this status
status (string) – (optional) trigger only when Thing is changed to this status
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ChannelEventTrigger(channelUID, event=None, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a ChannelEventTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ChannelEventTrigger("astro:sun:local:eclipse#event", "START", "solar-eclipse-event-start").trigger]

Parameters

channelUID (string) – name of the Channel to watch for trigger events
event (string) – (optional) trigger only when Channel triggers this event
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.GenericEventTrigger(eventSource, eventTypes, eventTopic='smarthome/*', triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a GenericEventTrigger Module to be used when creating a Rule. It allows you to trigger on any event that comes through the Event Bus. It’s one of the the most powerful triggers, but it is also the most complicated to configure.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [GenericEventTrigger("smarthome/items/Test_Switch_1/", "ItemStateEvent", "smarthome/items/*", "Test_Switch_1-received-update").trigger]

Parameters

eventSource (string) – source to watch for trigger events
eventTypes (string or list) – types of events to watch
eventTopic (string) – (optional) topic to watch
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemEventTrigger(eventSource, eventTypes, eventTopic='smarthome/items/*', triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class is the same as the GenericEventTrigger, but simplifies it a bit for use with Items. The available Item eventTypes are:

"ItemStateEvent" (Item state update)
"ItemCommandEvent" (Item received Command)
"ItemStateChangedEvent" (Item state changed)
"GroupItemStateChangedEvent" (GroupItem state changed)

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemEventTrigger("Test_Switch_1", "ItemStateEvent", "smarthome/items/*").trigger]

Parameters

eventSource (string) – source to watch for trigger events
eventTypes (string or list) – types of events to watch
eventTopic (string) – (optional) topic to watch (no need to change default)
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ThingEventTrigger(thingUID, eventTypes, eventTopic='smarthome/things/*', triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class is the same as the GenericEventTrigger, but simplifies it a bit for use with Things. The available Thing eventTypes are:

"ThingAddedEvent"
"ThingRemovedEvent"
"ThingStatusInfoChangedEvent"
"ThingStatusInfoEvent"
"ThingUpdatedEvent"

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ThingEventTrigger("kodi:kodi:familyroom", "ThingStatusInfoEvent").trigger]

Parameters

eventSource (string) – source to watch for trigger events
eventTypes (string or list) – types of events to watch
eventTopic (string) – (optional) topic to watch (no need to change default)
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.CronTrigger(cronExpression, triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a CronTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [CronTrigger("0 55 17 * * ?").trigger]

Parameters

cronExpression (string) – a valid cron expression
triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.StartupTrigger(triggerName=None)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a StartupTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [StartupTrigger().trigger]

Parameters: triggerName (string) – (optional) name of this trigger

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemRegistryTrigger(event_name)¶

Bases: core_mock.osgi.events.OsgiEventTrigger

This class builds an OsgiEventTrigger Module to be used when creating a Rule. Requires the 100_OsgiEventTrigger.py component script. The available Item registry event_names are:

"ItemAddedEvent"
"ItemRemovedEvent"
"ItemUpdatedEvent"

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemRegistryTrigger("ItemAddedEvent").trigger]

Parameters: event_name (string) – name of the event to watch

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemAddedTrigger¶

Bases: core.triggers.ItemRegistryTrigger

This class is the same as the ItemRegistryTrigger, but limited to when an Item is added. This trigger will fire when any Item is added.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemAddedTrigger().trigger]

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemRemovedTrigger¶

Bases: core.triggers.ItemRegistryTrigger

This class is the same as the ItemRegistryTrigger, but limited to when an Item is removed. This trigger will fire when any Item is removed.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemRemovedTrigger().trigger]

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.ItemUpdatedTrigger¶

Bases: core.triggers.ItemRegistryTrigger

This class is the same as the ItemRegistryTrigger, but limited to when an Item is updated. This trigger will fire when any Item is updated.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemUpdatedTrigger().trigger]

trigger¶

Trigger object to be added to a Rule

Type: Trigger

class core.triggers.DirectoryEventTrigger(path, event_kinds=[java.nio.file.StandardWatchEventKinds.ENTRY_CREATE, java.nio.file.StandardWatchEventKinds.ENTRY_DELETE, java.nio.file.StandardWatchEventKinds.ENTRY_MODIFY], watch_subdirectories=False)¶

Bases: core_mock.jsr223.scope.Trigger

This class builds a DirectoryEventTrigger Module to be used when creating a Rule. Requires the 100_DirectoryTrigger.py component script.

See Extensions for examples of how to use these extensions.

Parameters

path (string) – path of the directory to watch
event_kinds (list) – (optional) list of the events to watch for
watch_subdirectories (Boolean) – (optional) True will watch subdirectories

trigger¶

Trigger object to be added to a Rule

Type: Trigger

core.triggers¶

core.triggers ¶